Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

nice_things/collections/Array.sh

The Array class implements an array type in pure POSIX sh. It exists because List—the only way to represent structured data in sh—is lossy. The classes provided by the framework in the collections directory aim to bring robust data structure types to POSIX sh, and Array is one of those types.

The API is influenced by JavaScript Arrays. Method signatures are as close to that API as is possible to do in sh. One exception is indexing, which starts from 1, as is common in sh, and go up to length inclusive. Methods that take an index argument also accept negative numbers to search from the end of the Array.

Being a class, while working with Array, you will be passing references around. The internal state of the object is managed by the framework's object system, you only have to keep a reference to it. The constructor returns a reference, and every method is this class take that reference as the first argument. The user is responsible for calling the destructor method to free the resources used by the object.

There are many ways to iterate over the Array. You can loop over the indexes from 1 to length inclusive, calling the get method on each index. Or you can consume the Array in a loop with the pop or shift methods.

Usage examples

# Create an Array: letters=[a,b]
letters=#{{{ new Array }}} a b

# Add elements to the Array: letters=[a,b,c,d]
Array_push "$letters" c d

# Get the length of the Array
Array_length "$letters" length

# Iterate over all elements of the Array
index=1
while [ "$index" -le "$length" ]; do
	Array_get "$letters" element "$index"
	# Do something with "$element"
	# ...
	index=$((index + 1))
done

# Destroy the Array
Array_destructor "$letters"

Array

Since 0.3.0 · Source 

import "{ Array }" from nice_things/collections/Array.sh

Synopsis
Array <&self> [<element>…]

Configuration
–

Description
Constructor for the Array class. Can optionally take initial state as arguments.

Usually, this constructor function should be invoked with the new macro, which takes care of creating the <&self> reference to the newly created object.

Options
–

Operands

  • <out_var>: Output variable; the result will be written to this variable.
  • <element>: Element to push to the new Array.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e

Array_destructor

Since 0.3.0 · Source 

import "{ Array_destructor }" from nice_things/collections/Array_destructor.sh

Synopsis
Array_destructor <&self>

Configuration
–

Description
Clear all data associated with the object.

Options
–

Operands
<&self>: Self reference.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

Array_destructor "$array"

Array_get

Since 0.3.0 · Source 

import "{ Array_get }" from nice_things/collections/Array_get.sh

Synopsis
Array_get <&self> <out_var> <index>

Configuration
–

Description
Get an element from the Array by index.

<index> starts from 1 and go to the length of the Array inclusive.

Negative <index> can be used to count from the end of the Array, where -1 retrieves the last element, and -length the first.

The error code 1 will be returned if <index> is out-of-bounds.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.
  • <index>: Index of the element to retrieve starting from 1.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 1: <index> out-of-bounds.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e
Array_get "$letters" letter -2
log_debug "$letter" # d

Array_includes

Since 0.3.0 · Source 

import "{ Array_includes }" from nice_things/collections/Array_includes.sh

Synopsis
Array_includes <&self> <element>

Configuration
–

Description
Test if <element> is included in the Array. Return status code 0 if true, 1 if false.

Options
–

Operands

  • <&self>: Self reference.
  • <element>: The value to search.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: <element> is included in the Array.
  • 1: <element> is not included in the Array.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e
if Array_includes "$letters" d; then
	log_debug "'d' is included"
fi

Array_index_of

Since 0.3.0 · Source 

import "{ Array_index_of }" from nice_things/collections/Array_index_of.sh

Synopsis
Array_index_of <&self> <out_var> <element>

Configuration
–

Description
Get the index of the first occurrence of <element> in the Array. Return status code 0 if <element> is found in the Array, 1 if not found.

Note

This operation is slower than most other methods in this class.
If you don't need the index and are only testing for an element's existence, use the faster Array_includes instead.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.
  • <element>: The value to search.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: <element> found in the Array.
  • 1: <element> not found in the Array.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e
if Array_index_of "$letters" index d; then
	log_debug "'d' is at index ${index}" # 'd' is at index 4
fi

Array_length

Since 0.3.0 · Source 

import "{ Array_length }" from nice_things/collections/Array_length.sh

Synopsis
Array_length <&self> <out_var>

Configuration
–

Description
Get the length of the Array.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e
Array_length "$letters" len
log_debug "$len" # 5

Array_pop

Since 0.3.0 · Source 

import "{ Array_pop }" from nice_things/collections/Array_pop.sh

Synopsis
Array_pop <&self> [<out_var>]

Configuration
–

Description
Remove the last element from the Array. The removed element is assigned to <out_var>.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 1: No element removed; the Array is empty.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e
Array_pop "$letters" letter
log_debug "$letter" # e

Array_push

Since 0.3.0 · Source 

import "{ Array_push }" from nice_things/collections/Array_push.sh

Synopsis
Array_push <&self> <element>…

Configuration
–

Description
Add elements to the end of the Array.

Options
–

Operands

  • <&self>: Self reference.
  • <element>: An element to be added to the Array.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c
Array_push "$letters" d e f # a b c d e f

Array_shift

Since 0.3.0 · Source 

import "{ Array_shift }" from nice_things/collections/Array_shift.sh

Synopsis
Array_shift <&self> [<out_var>]

Configuration
–

Description
Remove the first element from the Array. The removed element is assigned to <out_var>.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 1: No element removed; the Array is empty.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e
Array_shift "$letters" letter
log_debug "$letter" # a

Array_slice

Since 0.3.0 · Source 

import "{ Array_slice }" from nice_things/collections/Array_slice.sh

Synopsis
Array_slice <&self> <out_var>

Configuration
–

Description
Clone the Array. The new Array is assigned to <out_var>.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

Array_slice "$array" slice

Array_splice

Since 0.3.0 · Source 

import "{ Array_splice }" from nice_things/collections/Array_splice.sh

Synopsis
Array_splice <&self> <index> <delete_count> [<element>…]

Configuration
–

Description
Mutate the Array by deleting and/or adding elements at the specific <index>.

<index> starts from 1 and can go up beyond the length of the Array. Adding elements beyond the end of the Array with this method do not make it sparse. When index is greater than the length of the Array, the first new element will be inserted at length + 1.

Negative <index> can be used to count from the end of the Array, where -1 is the last element, and -length the first.

<delete_count> is mandatory and should be set to 0 if you do not want to delete any elements.

Options
–

Operands

  • <&self>: Self reference.
  • <index>: Index at which to start changing the array.
  • <delete_count>: The number of elements to delete.
  • <element>: Value to add to the Array.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e
Array_splice "$letters" 3 2 C D # a b C D e

Array_to_quoted

Since 0.3.0 · Source 

import "{ Array_to_quoted }" from nice_things/collections/Array_to_quoted.sh

Synopsis
Array_to_quoted <&self> <out_var>

Configuration
–

Description
Get a quoted textual representation of the Array that is appropriate to use as an argument to the eval builtin command.

Options
–

Operands

  • <&self>: Self reference.
  • <out_var>: Output variable; the result will be written to this variable.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} a b c d e
Array_to_quoted "$letters" quoted_letters # "'a' 'b' 'c' 'd' 'e'"

Array_unshift

Since 0.3.0 · Source 

import "{ Array_unshift }" from nice_things/collections/Array_unshift.sh

Synopsis
Array_unshift <&self> <element>…

Configuration
–

Description
Add elements to the beginning of the Array.

Options
–

Operands

  • <&self>: Self reference.
  • <element>: An element to be added to the Array.

Stdin
–

Stdout
–

Stderr
–

Exit status

  • 0: Successful completion.
  • 12: Invalid self reference <&self> (abort).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

letters=#{{{ new Array }}} d e f
Array_unshift "$letters" a b c # a b c d e f